Перейти к основному содержимому

Архивация документов — никогда не удалять

Версия: 1.0 Дата: 25.04.2026 Статус: Готов к обсуждению

Документ описывает обязательный порядок архивации при замене старого документа новой версией. Закон системы документации: содержимое архивного документа никогда не удаляется — оно сохраняется как историческая запись.

Принцип​

Документация — слой принимаемых решений. Каждое решение имеет историю: контекст, в котором оно принято; альтернативы, которые рассматривались; условия, которые сделали его оправданным.

Когда документ заменяется новой версией, исходные формулировки сохраняются в виде архивного документа. Это нужно для:

  • понимания, почему было принято старое решение, и что изменилось;
  • разрешения противоречий между новой и старой логикой при ревью;
  • восстановления контекста, если новый документ окажется ошибочным;
  • честного аудита истории архитектурных решений (audit trail);
  • поиска и индексации старых формулировок через DocMap.

Удаление старого документа стирает контекст. Это запрещено.

Порядок архивации​

1. Переименование исходного документа​

docs_rename_file(
  old_file="reference/имя-документа.md",
  new_file="reference/имя-документа-old-2026-04-25.md",
  project="<slug>"
)

Суффикс -old-YYYY-MM-DD обязателен. Дата — день архивации (не день создания исходного документа).

2. Правка frontmatter архивного документа​

Frontmatter обновляется минимально — добавляется метка «архивная версия» в title::

---
title: "Оригинальное название (архивная версия 2.0)"
draft: false
---

draft: false сохраняется — архивные документы остаются индексируемыми DocMap, видимыми в production build, доступными для поиска. Это часть принципа «не стираем».

3. Правка шапки документа​

H1 и шапка обновляются — добавляется метка архивации, статус и предупреждение со ссылкой на новый документ:

# Оригинальное название (архивная версия 2.0)

**Версия:** 2.0 (архивная)
**Дата:** [исходная дата создания] (создание), ДД.ММ.ГГГГ (архивация)
**Статус:** Черновик (архивная версия)

> ⚠ **Этот документ переведён в архивный режим ДД.ММ.ГГГГ.** Актуальная версия — [Имя нового документа](Имя%20нового%20документа.md). Документ сохранён как историческая запись принятых решений.

Поля шапки:

  • **Версия:** — повышается на единицу относительно текущей и помечается «(архивная)». Если архивируется v1.0 при выпуске v2.0 — архив получает метку «2.0 (архивная)», новый документ становится «2.0».
  • **Дата:** — две даты: исходная дата создания + дата архивации.
  • **Статус:** — Черновик (архивная версия). Этот статус специально выделен, чтобы CMS-редактор и читатель сразу видели, что документ не источник правды.
  • Предупреждение — обязательная блок-цитата сразу после шапки, через пустую строку. В цитате — дата архивации и markdown-ссылка на актуальный документ.

4. Содержимое — не трогать​

Тело архивного документа (весь текст после шапки) не редактируется. Исторические формулировки сохраняются как есть.

Исключение — если в теле документа были <digit конструкции, ломающие MDX (см. MDX-безопасное написание). Только эти точечные правки разрешены, чтобы архив не ломал сборку.

5. Создание новой версии​

Новый документ создаётся через docs_create_file с именем без суффикса:

docs_create_file(
  file="reference/имя-документа.md",
  content="<новое содержимое>",
  project="<slug>"
)

В шапке нового документа:

# Оригинальное название (новая редакция)

**Версия:** 2.0
**Дата:** ДД.ММ.ГГГГ
**Статус:** Готов к обсуждению

> ⚠ **Эта редакция заменяет предыдущую версию.** Архивная версия — [Имя документа (архивная версия)](Имя%20документа-old-ДД.ММ.ГГГГ.md). Документ перепроектирован полностью с учётом следующих изменений: [перечисление].

6. Обновление обратных ссылок​

После архивации:

docs_links(section_id="<archived_section_id>", direction="from")

Список документов, ссылающихся на старое имя файла. В каждом из них — обновить ссылку либо на новое имя файла (если ссылка должна вести на актуальную версию), либо оставить ссылку на архив (если контекст требует исторической точки).

При большом числе backlinks — массовая замена через sed:

find docs/<slug> -name '*.md' -exec sed -i 's|имя-документа\.md|имя-документа.md|g' {} \;

Но безопаснее — точечно через docs_patch_section каждой секции с обоснованием, на что меняется ссылка.

Запрещённые паттерны​

  • ❌ Удаление содержимого архивного документа.
  • ❌ docs_delete_file для замены документа новой версией. Удаление допустимо только для документов-ошибок, созданных по случайности и не несущих информации.
  • ❌ Архивация без предупреждения со ссылкой на новый документ.
  • ❌ Архивация без статуса Черновик (архивная версия) — иначе читатель не отличит архив от актуального документа.
  • ❌ Перенос архивного документа в _old/ или archive/ папку — DocMap индексирует все четыре стандартных раздела, перенос ломает связи. Архив остаётся в исходном разделе с суффиксом -old-YYYY-MM-DD.
  • ❌ Изменение draft: false на draft: true для архива — архивы остаются видимыми и индексируемыми.

Случай из практики​

25 апреля 2026 — переработка верхнего слоя vitiana-api-platform/overview/. Старая index.md версии 2.0 заменена на v3.0 с правилом 00000 во главе. Старая layers.md v2.0 — заменена на v3.0 с шестью архитектурными осями.

Корректное действие:

  1. docs_rename_file overview/index.md → overview/index-old-2026-04-25.md.
  2. docs_patch_section шапки архива — статус Черновик (архивная версия), предупреждение со ссылкой на новую index.md.
  3. docs_create_file overview/index.md с содержимым v3.0.
  4. tools/build_project_index.sh vitiana-api-platform — но внимание: index.md проекта генерируется автоматически и не может быть архивирован напрямую. Здесь архивировался файл-секция, а не сам генерируемый index.md.

Содержимое старых документов сохранено целиком, доступно через docs_search для исторического контекста.

Связанная документация​